fix(backend): Fix JWT array audience validation by jescalan · Pull Request #8470 · clerk/javascript

jescalan · 2026-05-04T19:11:28Z

Summary

This fixes JWT audience validation for tokens whose aud claim is an array.

verifyJwt now passes the raw aud claim and configured audience option into assertAudienceClaim. The assertion helper already normalizes string and string-array inputs, so this lets it evaluate array audiences correctly.

Scope

This does not mean default Clerk session tokens have an aud claim. They generally do not, and this PR does not change the existing behavior for tokens with no aud: if the token has no audience claim, verifyJwt still skips audience validation.

The bug only applies when both of these are true:

the caller configured audience
the token payload contains aud as a string array

That shape is valid JWT syntax and is already represented in this package's M2M token parsing fallback (aud?: string[]). Clerk-issued M2M tokens also allow custom claims, and aud is not reserved there. So the fix is scoped to correctly enforcing the existing audience option when an array aud is present, not to introducing audience binding for all Clerk tokens.

Root Cause

verifyJwt wrapped both values before calling the assertion:

assertAudienceClaim([aud], [audience]);

When the token already had aud as a string array, the assertion received a nested array. That shape skipped both validation branches: it was not a string, and it was not an array of strings. The function returned without enforcing the configured audience.

Tests

Added assertion coverage for two string arrays with no intersection.
Added verifier coverage using signed JWTs:
- accepts an array aud when it includes the configured audience
- rejects an array aud when it does not include the configured audience

Validation

NODE_OPTIONS=--no-experimental-webstorage pnpm --filter @clerk/backend build
pnpm --filter @clerk/backend build:runtime
NODE_OPTIONS=--no-experimental-webstorage pnpm exec vitest run src/jwt/__tests__/assertions.test.ts src/jwt/__tests__/verifyJwt.test.ts --environment node --typecheck.enabled=false
pnpm --filter @clerk/backend format:check
git diff --check

vercel · 2026-05-04T19:11:33Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 13, 2026 7:54pm

changeset-bot · 2026-05-04T19:11:37Z

🦋 Changeset detected

Latest commit: 5c2ce3b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-05-04T19:21:50Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 9e5e5939-d952-4512-ba81-9ff9042b41b0

📥 Commits

Reviewing files that changed from the base of the PR and between 9416b81 and 5c2ce3b.

📒 Files selected for processing (1)

.changeset/seven-shoes-call.md

✅ Files skipped from review due to trivial changes (1)

.changeset/seven-shoes-call.md

📝 Walkthrough

Walkthrough

The pull request changes verifyJwt to call assertAudienceClaim(aud, audience) without wrapping values in arrays, and adds tests: one unit test for assertAudienceClaim that expects an error when audience arrays do not intersect, plus two verifyJwt tests that sign tokens with an array aud claim and check acceptance when the configured audience is present and rejection when it is absent.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main fix: JWT array audience validation for tokens with array-type aud claims.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the bug, fix, scope, and validation performed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

dominic-clerk

This could be for a follow-up but I think we could change the types in

javascript/packages/backend/src/jwt/assertions.ts

Line 10 in f2af9ba

export const assertAudienceClaim = (aud?: unknown, audience?: unknown) => {

from unknown to string | string[]

Also I understand skipping verification if we have no expected audience, but it seems odd to skip it if we do expect something and the token doesn't provide any.

javascript/packages/backend/src/jwt/assertions.ts

Line 13 in f2af9ba

const shouldVerifyAudience = audienceList.length > 0 && audList.length > 0;

pkg-pr-new · 2026-05-13T18:53:37Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8470

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8470

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8470

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8470

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8470

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8470

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8470

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8470

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8470

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8470

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8470

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8470

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8470

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8470

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8470

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8470

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8470

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8470

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8470

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8470

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8470

commit: 5c2ce3b

wobsoriano

@dominic-clerk approving as this fixes array aud handling and adds targeted coverage.

The type cleanup and missing aud behavior question can be a follow-up, right?

fix(backend): verify array jwt audiences

f2af9ba

github-actions Bot added the backend label May 4, 2026

vercel Bot deployed to Preview May 4, 2026 19:11 View deployment

jescalan changed the title ~~[codex] Fix JWT array audience validation~~ fix(backend): Fix JWT array audience validation May 4, 2026

jescalan requested review from brkalow, dominic-clerk and jacekradko and removed request for brkalow May 4, 2026 19:18

jescalan marked this pull request as ready for review May 4, 2026 19:18

dominic-clerk reviewed May 5, 2026

View reviewed changes

Merge branch 'main' into codex/fix-verify-token-array-aud

c5a870f

vercel Bot deployed to Preview May 13, 2026 18:51 View deployment

Merge branch 'main' into codex/fix-verify-token-array-aud

9416b81

vercel Bot deployed to Preview May 13, 2026 19:07 View deployment

chore: add changeset

5c2ce3b

vercel Bot deployed to Preview May 13, 2026 19:54 View deployment

wobsoriano approved these changes May 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(backend): Fix JWT array audience validation#8470

fix(backend): Fix JWT array audience validation#8470
jescalan wants to merge 4 commits into
mainfrom
codex/fix-verify-token-array-aud

jescalan commented May 4, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 4, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 4, 2026 •

edited

Loading

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

dominic-clerk left a comment •

edited

Loading

Uh oh!

pkg-pr-new Bot commented May 13, 2026 •

edited

Loading

Uh oh!

wobsoriano left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jescalan commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Scope

Root Cause

Tests

Validation

Uh oh!

vercel Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

dominic-clerk left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jescalan commented May 4, 2026 •

edited

Loading

vercel Bot commented May 4, 2026 •

edited

Loading

changeset-bot Bot commented May 4, 2026 •

edited

Loading

coderabbitai Bot commented May 4, 2026 •

edited

Loading

dominic-clerk left a comment •

edited

Loading

pkg-pr-new Bot commented May 13, 2026 •

edited

Loading